home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Toolbox / Visual Basic Toolbox (P.I.E.)(1996).ISO / compress / cxe103 / cx.doc next >
Text File  |  1992-08-03  |  22KB  |  559 lines
  1.  
  2.  
  3.  
  4.  
  5.                           Cx 1.03 - Data Compression Library   
  6.                                  July 30, 1992
  7.  
  8.  
  9.         !! IMPORTANT !!
  10.         ----------------------------------------------------------------
  11.           CXE103.EXE and all files contained within are Copyright (c)
  12.           1990-1992 Eugene Nelson.  The original file CXE103.EXE may be
  13.           distributed and used freely provided the intent of such
  14.           distribution/usage is for evaluating Cx for use in applications.
  15.  
  16.           CXE103.EXE contains an evaluation copy of the Cx Data Compression
  17.           Library.  Only one of the three data compression methods (Cx1) is
  18.           enabled in the evaluation version.
  19.  
  20.         Cx Features
  21.         -----------------------------------------------------------------
  22.           *  Versatile buffer based programming interface.
  23.  
  24.           *  Programmable memory requirements 16k-64k (plus buffers) when
  25.              compressing.  Only 5k (plus buffers) when decompressing.
  26.  
  27.           *  Three algorithms for different compression needs (speed vs.
  28.              size).
  29.  
  30.           *  Support for many compilers and environments, with functionally
  31.              identical ANSI C source code and 80x86 assembly source code
  32.              available.
  33.  
  34.           *  Optional Cyclical Redundancy Check (CRC) for error detection.
  35.  
  36.         Prices
  37.         -----------------------------------------------------------------
  38.           Cx 1.03 Commercial Version
  39.              -  Includes all three compression algorithms.
  40.              -  Purchaser granted the right to distribute CXWIN.DLL and
  41.                 CXOS2.DLL for use with applications.
  42.              -  Purchaser granted the right to use CX.OBJ, CX.TPU and CX.MIX
  43.                 in applications.
  44.              -  $45 (US)
  45.  
  46.           Cx 1.03 Commercial Version + Source
  47.              -  Cx 1.03 Commercial Version
  48.              -  ANSI C source code
  49.              -  80x86 assembly language source code
  50.              -  $95 (US)
  51.  
  52.           The rights described apply to Cx version 1.03.  Wisconsin residents
  53.           add 5% sales tax.  Non-USA residents add $5 (US).
  54.  
  55.           Send/Payable To:     Eugene Nelson
  56.                                955 E. Gorham
  57.                                Madison, WI 53703 USA
  58.  
  59.  
  60.  
  61.                                           1
  62.  
  63.  
  64.  
  65.  
  66.  
  67.         Files Included
  68.         -----------------------------------------------------------------
  69.           CX.DOC      -  This document.
  70.  
  71.           CX.OBJ      -  Cx 1.03 in OBJ format
  72.           CX.TPU      -  Cx 1.03 for Turbo Pascal
  73.           CX.MIX      -  Cx 1.03 for Power C
  74.           CXWIN.DLL   -  Cx 1.03 as a Windows DLL
  75.           CXWIN.LIB   -  Cx 1.03 import library for CXWIN.DLL
  76.           CXOS2.DLL   -  Cx 1.03 as an OS/2 DLL
  77.           CXOS2.LIB   -  Cx 1.03 import library for CXOS2.DLL
  78.  
  79.           CX.H        -  C interface to Cx
  80.           CXF.C       -  C example
  81.           CXF.PAS     -  Turbo Pascal example
  82.  
  83.           CXVB.BAS    -  Visual Basic interface to Cx
  84.           CXVB.FRM    -  Visual Basic example form
  85.           CXVB.MAK    -  Visual Basic example project
  86.  
  87.           MAKECXF.BAT -  Compiles CXF.EXE (MS-DOS and Windows)
  88.           MAKECXF.CMD -  Compiles CXF.EXE (OS/2)
  89.  
  90.           WINIO.OBJ   -  An object file that allows C based Windows programs
  91.                          to emulate console programs.  This data is provided
  92.                          courtesy of Microsoft Systems Journal, Andrew
  93.                          Schulman and Dave Maxey, and is available on
  94.                          Compuserve in the Microsoft Languages Forum (GO MSL)
  95.                          as files S13103.ZIP and S13155.ZIP.
  96.  
  97.  
  98.         Performance
  99.         -----------------------------------------------------------------
  100.           Cx currently supports three compression methods named Cx1, Cx2 and
  101.           Cx3.  Cx2 emphasizes overall performance, Cx1 emphasizes
  102.           compression and decompression speed and Cx3 emphasizes compression
  103.           size.
  104.  
  105.           The following data (sorted by size) was produced with a 286/12 MHZ
  106.           computer.
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.                                           2
  124.  
  125.  
  126.  
  127.  
  128.  
  129.              1MB of C source files (programming language)
  130.              METHOD            SIZE   COMPRESS TIME   DECOMPRESS TIME
  131.              --------------------------------------------------------     
  132.              ARJ 2.30          225,254           88                16
  133.              PKZIP 1.93        228,189           41                 9
  134.              LHA 2.13          250,000          111                15
  135.              ZOO 2.1           250,002          295                32
  136.             *Cx3               250,261           89                41
  137.              PKZIP 1.1         254,217           63                 8
  138.             *Cx2               256,547           74                25
  139.              PAK 2.51          263,998           90                19
  140.              LHARC 1.13c       279,364          178                32
  141.              Cx1               290,816           46                12
  142.              ARC 6.02          442,441           50                27
  143.  
  144.              1MB of AP wire stories (natural language, English)
  145.              METHOD            SIZE   COMPRESS TIME   DECOMPRESS TIME
  146.              --------------------------------------------------------
  147.              ARJ 2.30          394,880          112                22
  148.              PKZIP 1.93        397,616           64                12
  149.              LHA 2.13          439,037          123                24
  150.              ZOO 2.1           439,039          314                50
  151.              PKZIP 1.1         442,277           80                11
  152.             *Cx3               449,041          139                63
  153.              PAK 2.51          449,366           97                22
  154.             *Cx2               460,970          115                40
  155.              LHARC 1.13c       477,308          117                44
  156.              Cx1               531,648           65                20
  157.              ARC 6.02          607,023           61                33
  158.  
  159.              1MB of .EXE files (machine language)
  160.              METHOD            SIZE   COMPRESS TIME   DECOMPRESS TIME
  161.              --------------------------------------------------------
  162.              ARJ 2.30          549,538          119                27
  163.              PKZIP 1.93        550,472           66                14
  164.             *Cx3               559,911          213               115
  165.              LHA 2.13          568,383          113                28
  166.              ZOO 2.1           568,385          285                51
  167.             *Cx2               572,397          131                34
  168.              PAK 2.51          588,072          106                27
  169.              PKZIP 1.1         588,959           95                12
  170.              LHARC 1.13c       592,647          140                65
  171.              Cx1               606,952           74                21
  172.              ARC 6.02          770,919           69                37
  173.  
  174.           Although there are algorithms which are clearly superior to Cx, it
  175.           should be apparent that Cx is competitive.  Cx2 performs better
  176.           than LHARC 1.13c (perhaps the most popular archiver ever made) in
  177.           all measurements.  Cx1 provides acceptable compression with times
  178.           always in the top 3.
  179.  
  180.           * Not enabled in evaluation version.
  181.  
  182.  
  183.  
  184.  
  185.                                           3
  186.  
  187.  
  188.  
  189.  
  190.  
  191.         Programming Interface
  192.         -----------------------------------------------------------------
  193.          
  194.           Types and Constants
  195.           --------------------------------------------------------------
  196.              See file CX.H or VBCX.BAS for exact values of constants.
  197.  
  198.              CXINT             -  A 16 bit unsigned integer.
  199.              CXINTSIZE         -  The size of CXINT (2 bytes).
  200.              CXBUFF            -  A 32 bit pointer to a buffer.
  201.              CXCALL            -  32 bit (far) Pascal calling convention
  202.  
  203.              CX_ERR_INVALID    -  Error code returned by Cx routines.
  204.              CX_ERR_METHOD     -  ...
  205.              CX_ERR_BUFFSIZE   -  ...
  206.              CX_ERR_TEMPSIZE   -  ...
  207.  
  208.              CX_METHOD1        -  Identifies algorithm 1 (Cx1 above).
  209.              CX_METHOD2        -  Identifies algorithm 2 (Cx2 above).
  210.              CX_METHOD3        -  Identifies algorithm 3 (Cx3 above).
  211.  
  212.              CX_MAX_BUFFER     -  The maximum buffer size that may be
  213.                                   compressed.  Currently a little less than
  214.                                   64k.
  215.  
  216.              CX_SLOP           -  The amount the Cx routines may overrun
  217.                                   compressed buffers.  Currently about 300
  218.                                   bytes.
  219.  
  220.              CX_C_MINTEMP      -  The minimum amount of temporary memory the
  221.                                   Cx compression routines need.  Currently
  222.                                   16k.
  223.  
  224.              CX_C_MAXTEMP      -  The maximum amount of temporary memory the
  225.                                   Cx compression methods can use.  Currently
  226.                                   about 64k.
  227.  
  228.              CX_D_MINTEMP      -  The minimum amount of temporary memory the
  229.                                   Cx decompression routines need.  Currently
  230.                                   5k.
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.                                           4
  248.  
  249.  
  250.  
  251.  
  252.  
  253.           CXINT CXCALL CX_COMPRESS(  CXINT method,
  254.                                      CXBUFF obuff, CXINT osize,
  255.                                      CXBUFF ibuff, CXINT isize,
  256.                                      CXBUFF tbuff, CXINT tsize)
  257.           --------------------------------------------------------------
  258.           method   -  Method of data compression to use.  method must be
  259.                       CX_METHOD1, CX_METHOD2 or CX_METHOD3.
  260.  
  261.         >>>           THE ONLY METHOD SUPPORTED IN THE EVALUATION VERSION IS
  262.                       CX_METHOD1 !!!
  263.  
  264.           obuff    -  Output buffer where compressed data is to be placed.
  265.  
  266.           osize    -  Size of obuff.  osize must be within the range
  267.                       [0..CX_MAX_BUFFER].  CX_COMPRESS must have read/write
  268.                       access to bytes [0..osize+CX_SLOP] in obuff.
  269.  
  270.           ibuff    -  Input buffer containing data to compress.  The contents
  271.                       of ibuff are not modified by CX_COMPRESS.
  272.  
  273.           isize    -  Bytes of data in ibuff to compress.  isize must be
  274.                       within the range [0..CX_MAX_BUFFER]. 
  275.  
  276.           tbuff    -  A buffer that will be used by Cx for temporary storage.
  277.  
  278.           tsize    -  Size of tbuff.  Cx needs at least CX_C_MINTEMP bytes of
  279.                       temporary storage while compressing, but can make use
  280.                       of up to CX_C_MAXTEMP bytes.  The more temporary
  281.                       storage provided to Cx, the greater the potential for
  282.                       compression.  tsize must be within the range
  283.                       [CX_C_MINTEMP..CX_C_MAXTEMP].
  284.  
  285.           RETURN   -  CX_ERR_METHOD
  286.                       The compression method requested is invalid or
  287.                       unsupported in the called version of CX_COMPRESS.
  288.  
  289.                    -  CX_ERR_BUFFSIZE
  290.                       isize or osize is not within the range
  291.                       [0..CX_MAX_BUFFER].
  292.  
  293.                    -  CX_ERR_TEMPSIZE
  294.                       tsize is not within the range
  295.                       [CX_C_MINTEMP..CX_C_MAXTEMP].
  296.  
  297.                    -  isize
  298.                       The data in ibuff was not compressible.  In this case,
  299.                       no assumptions about the contents of obuff should be
  300.                       made.
  301.  
  302.                    -  OTHERWISE
  303.                       The data in ibuff was successfully compressed to obuff. 
  304.                       The return value is the number of compressed bytes
  305.                       placed in obuff.
  306.  
  307.  
  308.  
  309.                                           5
  310.  
  311.  
  312.  
  313.  
  314.  
  315.           CXINT CXCALL CX_DECOMPRESS(   CXBUFF obuff, CXINT osize, 
  316.                                         CXBUFF ibuff, CXINT isize,
  317.                                         CXBUFF tbuff, CXINT tsize)
  318.           --------------------------------------------------------------
  319.           obuff    -  Output buffer where decompressed data is to be placed.
  320.  
  321.           osize    -  Size of obuff.  Usually, osize will be the number of
  322.                       bytes that where compressed into ibuff, but osize may
  323.                       be smaller, allowing for partial decompression of a
  324.                       buffer.
  325.  
  326.           ibuff    -  Input buffer containing data compressed with Cx.  The
  327.                       contents of ibuff are not modified by CX_DECOMPRESS.
  328.  
  329.           isize    -  Size of ibuff.  CX_DECOMPRESS recognizes the end of the
  330.                       compressed data in ibuff by a special 'End of Data'
  331.                       symbol, NOT by consulting isize.  isize is used to
  332.                       prevent CX_DECOMPRESS from crashing when the data in
  333.                       ibuff is invalid or corrupt.  isize must be within the
  334.                       range [0..CX_MAX_BUFFER].   CX_DECOMPRESS must have
  335.                       read access to bytes [0..isize+CX_SLOP] in ibuff.
  336.  
  337.           tbuff    -  A buffer that will be used by Cx for temporary storage.
  338.  
  339.           tsize    -  Size of tbuff.  tsize must be at least CX_D_MINTEMP. 
  340.                       CX_DECOMPRESS does not need (and will not use) more
  341.                       than CX_D_MINTEMP bytes of temporary storage.
  342.  
  343.           RETURN   -  CX_ERR_METHOD
  344.                       The data in ibuff is invalid, corrupt, or was
  345.                       compressed with a method not supported in the called
  346.                       version of CX_DECOMPRESS.
  347.  
  348.                    -  CX_ERR_INVALID
  349.                       The data in ibuff is invalid or corrupt, and can not be
  350.                       completely decompressed.  In this case, CX_DECOMPRESS
  351.                       may be called with different values of osize to find
  352.                       the largest amount of data that can be decompressed
  353.                       without an error.  Note, however, that just because
  354.                       CX_DECOMPRESS does not return CX_ERR_INVALID does not
  355.                       necessarily mean the decompressed data placed in obuff
  356.                       is valid.  It simply means that no errors where
  357.                       detected.  This is why a checksum or CRC should be
  358.                       stored with compressed data to help detect errors.
  359.  
  360.                    -  CX_ERR_BUFFSIZE
  361.                       isize is not within the range [0..CX_MAX_BUFFER].
  362.  
  363.                    -  CX_ERR_TEMPSIZE
  364.                       tsize is smaller than CX_D_MINTEMP.
  365.  
  366.                    -  OTHERWISE
  367.                       The data in ibuff was successfully decompressed into
  368.                       obuff.  The return value is the number of decompressed
  369.                       bytes placed into obuff.
  370.  
  371.                                           6
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.           CXINT CXCALL CX_CRC(CXBUFF, buff, CXINT n)
  379.           -----------------------------------------------------------
  380.           buff     -  Buffer to compute Cyclical Redundancy Check (CRC) on.
  381.           n        -  Bytes in buff.
  382.  
  383.           RETURN   -  16 bit CRC.
  384.  
  385.  
  386.         Programming Notes
  387.         -----------------------------------------------------------------
  388.           -  When compressing, it is best to present as large a buffer as
  389.              possible to Cx.  60,000 bytes of data will be compressed better
  390.              when CX_COMPRESS is called once, as opposed to 6 times with
  391.              10,000 bytes.
  392.  
  393.           -  Both CX_COMPRESS and CX_DECOMPRESS are re-entrant, and may be
  394.              used in multi-tasking environments.
  395.  
  396.           -  CX_COMPRESS and CX_DECOMPRESS use less than 256 bytes of stack
  397.              space.
  398.  
  399.           -  CX_SLOP is needed for performance reasons.  Cx performs faster
  400.              when it is allowed to slightly overrun buffers that will or do
  401.              contain compressed data.  For example:
  402.  
  403.                 ibuff = allocate (k) bytes
  404.                 obuff = allocate (k+CX_SLOP) bytes  <- a little bigger than k
  405.  
  406.                 CX_COMPRESS(CX_METHOD1, obuff, k, ibuff, k, ...)
  407.  
  408.                 ibuff = allocate(k+CX_SLOP) bytes   <- a little bigger than k
  409.                 obuff = allocate(k) bytes
  410.  
  411.                 CX_DECOMPRESS(obuff, k, ibuff, k, ...)
  412.  
  413.           -  Currently, Power C users are unable to use CX.OBJ and must rely
  414.              upon CX.MIX.  CX.MIX is a large model only version of CX.OBJ. 
  415.              CX.MIX is derived from the ANSI C version of Cx, and does not
  416.              have the assembly language optimizations.
  417.  
  418.           -  CX.OBJ will work with all memory models, but it is important to
  419.              make sure that calls made to Cx are correct.  Far pointers to
  420.              data, a far call, and the Pascal calling convention.
  421.  
  422.           -  When speed is the primary issue, consider a checksum or no error
  423.              detection instead of CX_CRC.  The time needed by CX_CRC compared
  424.              to CX_COMPRESS and CX_DECOMPRESS is not always insignificant.
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.                                           7
  434.  
  435.  
  436.  
  437.  
  438.  
  439.         The Example CXF.EXE
  440.         -----------------------------------------------------------------
  441.           CXF.EXE will compress and decompress a file of any size and of any
  442.           type of data.  The source for cxf.exe is contained in the files:
  443.  
  444.              cxf.c
  445.              cxf.pas
  446.  
  447.           These files demonstrate the suggested usage for Cx.  Note the
  448.           following:
  449.  
  450.              -  A CRC is computed on the compressed buffer, NOT the original
  451.                 data.  This allows decompression of partial buffers, without
  452.                 the need for an additional CRC, and has proven to be more
  453.                 reliable.  Of course, a CRC on the original data could also
  454.                 be stored.
  455.  
  456.              -  Both the size of the original data and compressed data are
  457.                 stored.  This allows storage of incompressible data, and
  458.                 provides any easy way to check if the stored buffer is
  459.                 compressed.
  460.  
  461.           To compile CXF.EXE simply run the batch file MAKECXF.BAT
  462.           (MAKECXF.CMD for OS/2) and follow the instructions.
  463.  
  464.  
  465.         Low Memory Situations
  466.         -----------------------------------------------------------------
  467.           As stated, it is best to present large buffers to CX_COMPRESS for
  468.           maximum compression.  At most, this could amount to three 64k
  469.           buffers (approximate), or 192k.  If this is not acceptable, the
  470.           input and output buffers can be made smaller, and/or the temporary
  471.           storage size reduced.  As an extreme example, 8k buffers could be
  472.           used for input and output with temporary storage of 16k
  473.           (CX_C_MINTEMP), for a total of 32k.  The only way to find an
  474.           acceptable solution is to experiment with buffer sizes.  It may
  475.           also be helpful to pass an output buffer smaller than the input
  476.           buffer when compressing in the hope that the compressed data will
  477.           fit.
  478.  
  479.           When decompressing, there are not many alternatives because
  480.           decompression is based on the original buffer sizes.  Note,
  481.           however, the temporary storage required when decompressing is less
  482.           (5k).
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.                                           8
  496.  
  497.  
  498.  
  499.  
  500.  
  501.         Interfacing to CX.OBJ
  502.         -----------------------------------------------------------------
  503.           The compilers tested which use CX.OBJ have simply needed to link it
  504.           in.  If problems arise when using a compiler that has not been
  505.           tested, the following notes about CX.OBJ may be helpful:
  506.  
  507.              -  Only one segment is used, and it has the following
  508.                 definition:
  509.  
  510.                    CODE      SEGMENT BYTE PUBLIC 'CODE'
  511.  
  512.              -  All buffers passed are 32 pointers.
  513.  
  514.              -  A far call should be placed to all routines.
  515.  
  516.              -  The pascal calling convention is used.  As an example, CX_CRC
  517.                 looks like:
  518.  
  519.                    CXINT CX_CRC(CXBUFF, buff, CXINT n)
  520.                    {
  521.                       push  bp
  522.                       mov   bp,sp
  523.                       ...
  524.                       mov   sp,bp
  525.                       pop   bp
  526.                       retf  6
  527.                    }
  528.  
  529.                 buff is located in bytes bp[8..11] and n is located in bytes
  530.                 bp[6..7].  The result is returned in AX.
  531.  
  532.              -  The direction flag is assumed to be cleared, and is returned
  533.                 unaltered.
  534.  
  535.              -  The following registers and 'normal' flags may be altered:
  536.  
  537.                    AX, BX, CX, DX, ES
  538.  
  539.  
  540.         More Information
  541.         -----------------------------------------------------------------
  542.           For further information contact the address listed above or Eugene
  543.           Nelson at Compuserve ID 70662,2501.
  544.  
  545.  
  546.         Disclaimer
  547.         -----------------------------------------------------------------
  548.           Eugene Nelson hereby disclaims all warranties relating to this
  549.           software, whether express or implied, including without limitation
  550.           any implications of suitability for a given purpose.  Eugene Nelson
  551.           will not be liable for any direct, incidental, consequential or
  552.           other damage resulting from the use of this software.
  553.  
  554.  
  555.  
  556.  
  557.                                           9
  558.  
  559.